NIFI-14144 Declare status code and content for success in OpenAPI spec #9629
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
There was a problem hiding this comment.
Thanks for working on this substantive adjustment @EndzeitBegins.
It seems like the best way to go, as it aligns the successful response type with the defined schema, as opposed to setting the default value.
Are you aware of any issues with removing the default response value as shown after these change?
|
Thank you for your review @exceptionfactory. I'm not aware of any significant issues arising from these changes. As expected, the modifications primarily impact the generated documentation regarding responses and status codes, when comparing outputs from Notably, a few endpoints previously defined in the original swagger.json (prior to these changes) erroneously returned
Here an example of the generated code snippets. Code generated before PR (excerpt)
/**
* Creates a request to drop the contents of the queue in this connection.
*
* @param id The connection id. (required)
* @throws ApiException If fail to call the API, e.g. server error or cannot deserialize the response body
* @http.response.details
<table border="1">
<caption>Response Details</caption>
<tr><td> Status Code </td><td> Description </td><td> Response Headers </td></tr>
<tr><td> 202 </td><td> The request has been accepted. A HTTP response header will contain the URI where the response can be polled. </td><td> - </td></tr>
<tr><td> 400 </td><td> NiFi was unable to complete the request because it was invalid. The request should not be retried without modification. </td><td> - </td></tr>
<tr><td> 401 </td><td> Client could not be authenticated. </td><td> - </td></tr>
<tr><td> 403 </td><td> Client is not authorized to make this request. </td><td> - </td></tr>
<tr><td> 404 </td><td> The specified resource could not be found. </td><td> - </td></tr>
<tr><td> 409 </td><td> The request was valid but NiFi was not in the appropriate state to process it. </td><td> - </td></tr>
</table>
*/
public void createDropRequest(String id) throws ApiException {
createDropRequestWithHttpInfo(id);
}Code generated after PR (excerpt)
/**
* Creates a request to drop the contents of the queue in this connection.
*
* @param id The connection id. (required)
* @return DropRequestEntity
* @throws ApiException If fail to call the API, e.g. server error or cannot deserialize the response body
* @http.response.details
<table border="1">
<caption>Response Details</caption>
<tr><td> Status Code </td><td> Description </td><td> Response Headers </td></tr>
<tr><td> 202 </td><td> The request has been accepted. A HTTP response header will contain the URI where the response can be polled. </td><td> - </td></tr>
<tr><td> 400 </td><td> NiFi was unable to complete the request because it was invalid. The request should not be retried without modification. </td><td> - </td></tr>
<tr><td> 401 </td><td> Client could not be authenticated. </td><td> - </td></tr>
<tr><td> 403 </td><td> Client is not authorized to make this request. </td><td> - </td></tr>
<tr><td> 404 </td><td> The specified resource could not be found. </td><td> - </td></tr>
<tr><td> 409 </td><td> The request was valid but NiFi was not in the appropriate state to process it. </td><td> - </td></tr>
</table>
*/
public DropRequestEntity createDropRequest(String id) throws ApiException {
ApiResponse<DropRequestEntity> localVarResp = createDropRequestWithHttpInfo(id);
return localVarResp.getData();
}This was the case, because they had both a success response (but without content) and a default response with content defined. Due to the success response being present, the content defined in the default response had no effect on the generated response type. swagger.json before PR (excerpt)
...
"/flowfile-queues/{id}/drop-requests" : {
"post" : {
"operationId" : "createDropRequest",
...
"responses" : {
"202" : {
"description" : "The request has been accepted. A HTTP response header will contain the URI where the response can be polled."
},
"400" : {
"description" : "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."
},
"401" : {
"description" : "Client could not be authenticated."
},
"403" : {
"description" : "Client is not authorized to make this request."
},
"404" : {
"description" : "The specified resource could not be found."
},
"409" : {
"description" : "The request was valid but NiFi was not in the appropriate state to process it."
},
"default" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DropRequestEntity"
}
}
}
}
},
...swagger.json after PR (excerpt)
...
"/flowfile-queues/{id}/drop-requests" : {
"post" : {
"operationId" : "createDropRequest",
...
"responses" : {
"202" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DropRequestEntity"
}
}
},
"description" : "The request has been accepted. A HTTP response header will contain the URI where the response can be polled."
},
"400" : {
"description" : "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."
},
"401" : {
"description" : "Client could not be authenticated."
},
"403" : {
"description" : "Client is not authorized to make this request."
},
"404" : {
"description" : "The specified resource could not be found."
},
"409" : {
"description" : "The request was valid but NiFi was not in the appropriate state to process it."
}
},
...
}, |
exceptionfactory
approved these changes
Jan 22, 2025
There was a problem hiding this comment.
Thanks for the reply and additional explanation @EndzeitBegins. Great to have these corrections and improvements to the OpenAPI specification! +1 merging
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
NIFI-14144
swagger.json before change (excerpt)
{ "/access/token" : { "post" : { "description" : "The token returned is formatted as a JSON Web Token (JWT). The token is base64 encoded and comprised of three parts. The header, the body, and the signature. The expiration of the token is a contained within the body. It is stored in the browser as a cookie, but also returned inthe response body to be stored/used by third party client scripts.", "operationId" : "createAccessToken", "requestBody" : { "content" : { "application/x-www-form-urlencoded" : { "schema" : { "type" : "object", "properties" : { "password" : { "type" : "string" }, "username" : { "type" : "string" } } } } } }, "responses" : { "400" : { "description" : "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification." }, "403" : { "description" : "Client is not authorized to make this request." }, "409" : { "description" : "The request was valid but NiFi was not in the appropriate state to process it." }, "500" : { "description" : "Unable to create access token because an unexpected error occurred." }, "default" : { "content" : { "text/plain" : { "schema" : { "type" : "string" } } } } }, "summary" : "Creates a token for accessing the REST API via username/password", "tags" : [ "Access" ] } } }swagger.json after change (excerpt)
{ "/access/token" : { "post" : { "description" : "The token returned is formatted as a JSON Web Token (JWT). The token is base64 encoded and comprised of three parts. The header, the body, and the signature. The expiration of the token is a contained within the body. It is stored in the browser as a cookie, but also returned inthe response body to be stored/used by third party client scripts.", "operationId" : "createAccessToken", "requestBody" : { "content" : { "application/x-www-form-urlencoded" : { "schema" : { "type" : "object", "properties" : { "password" : { "type" : "string" }, "username" : { "type" : "string" } } } } } }, "responses" : { "201" : { "content" : { "text/plain" : { "schema" : { "type" : "string" } } } }, "400" : { "description" : "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification." }, "403" : { "description" : "Client is not authorized to make this request." }, "409" : { "description" : "The request was valid but NiFi was not in the appropriate state to process it." }, "500" : { "description" : "Unable to create access token because an unexpected error occurred." } }, "summary" : "Creates a token for accessing the REST API via username/password", "tags" : [ "Access" ] } } }Tracking
Please complete the following tracking steps prior to pull request creation.
Issue Tracking
Pull Request Tracking
NIFI-00000NIFI-00000Pull Request Formatting
mainbranchVerification
Please indicate the verification steps performed prior to pull request creation.
Build
mvn clean install -P contrib-checkLicensing
LICENSEandNOTICEfilesDocumentation